home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / zgges.z / zgges
Encoding:
Text File  |  2002-10-03  |  9.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))                                                            ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZGGES - compute for a pair of N-by-N complex nonsymmetric matrices (A,B),
  10.      the generalized eigenvalues, the generalized complex Schur form (S, T),
  11.      and optionally left and/or right Schur vectors (VSL and VSR)
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE ZGGES( JOBVSL, JOBVSR, SORT, DELCTG, N, A, LDA, B, LDB, SDIM,
  15.                        ALPHA, BETA, VSL, LDVSL, VSR, LDVSR, WORK, LWORK,
  16.                        RWORK, BWORK, INFO )
  17.  
  18.          CHARACTER     JOBVSL, JOBVSR, SORT
  19.  
  20.          INTEGER       INFO, LDA, LDB, LDVSL, LDVSR, LWORK, N, SDIM
  21.  
  22.          LOGICAL       BWORK( * )
  23.  
  24.          DOUBLE        PRECISION RWORK( * )
  25.  
  26.          COMPLEX*16    A( LDA, * ), ALPHA( * ), B( LDB, * ), BETA( * ), VSL(
  27.                        LDVSL, * ), VSR( LDVSR, * ), WORK( * )
  28.  
  29.          LOGICAL       DELCTG
  30.  
  31.          EXTERNAL      DELCTG
  32.  
  33. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  34.      These routines are part of the SCSL Scientific Library and can be loaded
  35.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  36.      directs the linker to use the multi-processor version of the library.
  37.  
  38.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  39.      4 bytes (32 bits). Another version of SCSL is available in which integers
  40.      are 8 bytes (64 bits).  This version allows the user access to larger
  41.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  42.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  43.      only one of the two versions; 4-byte integer and 8-byte integer library
  44.      calls cannot be mixed.
  45.  
  46. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  47.      ZGGES computes for a pair of N-by-N complex nonsymmetric matrices (A,B),
  48.      the generalized eigenvalues, the generalized complex Schur form (S, T),
  49.      and optionally left and/or right Schur vectors (VSL and VSR). This gives
  50.      the generalized Schur factorization
  51.              (A,B) = ( (VSL)*S*(VSR)**H, (VSL)*T*(VSR)**H )
  52.  
  53.      where (VSR)**H is the conjugate-transpose of VSR.
  54.  
  55.      Optionally, it also orders the eigenvalues so that a selected cluster of
  56.      eigenvalues appears in the leading diagonal blocks of the upper
  57.      triangular matrix S and the upper triangular matrix T. The leading
  58.      columns of VSL and VSR then form an unitary basis for the corresponding
  59.      left and right eigenspaces (deflating subspaces).
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))                                                            ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      (If only the generalized eigenvalues are needed, use the driver ZGGEV
  75.      instead, which is faster.)
  76.  
  77.      A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or a
  78.      ratio alpha/beta = w, such that  A - w*B is singular.  It is usually
  79.      represented as the pair (alpha,beta), as there is a reasonable
  80.      interpretation for beta=0, and even for both being zero.
  81.  
  82.      A pair of matrices (S,T) is in generalized complex Schur form if S and T
  83.      are upper triangular and, in addition, the diagonal elements of T are
  84.      non-negative real numbers.
  85.  
  86.  
  87. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  88.      JOBVSL  (input) CHARACTER*1
  89.              = 'N':  do not compute the left Schur vectors;
  90.              = 'V':  compute the left Schur vectors.
  91.  
  92.      JOBVSR  (input) CHARACTER*1
  93.              = 'N':  do not compute the right Schur vectors;
  94.              = 'V':  compute the right Schur vectors.
  95.  
  96.      SORT    (input) CHARACTER*1
  97.              Specifies whether or not to order the eigenvalues on the diagonal
  98.              of the generalized Schur form.  = 'N':  Eigenvalues are not
  99.              ordered;
  100.              = 'S':  Eigenvalues are ordered (see DELCTG).
  101.  
  102.      DELCTG  (input) LOGICAL FUNCTION of two COMPLEX*16 arguments
  103.              DELCTG must be declared EXTERNAL in the calling subroutine.  If
  104.              SORT = 'N', DELCTG is not referenced.  If SORT = 'S', DELCTG is
  105.              used to select eigenvalues to sort to the top left of the Schur
  106.              form.  An eigenvalue ALPHA(j)/BETA(j) is selected if
  107.              DELCTG(ALPHA(j),BETA(j)) is true.
  108.  
  109.              Note that a selected complex eigenvalue may no longer satisfy
  110.              DELCTG(ALPHA(j),BETA(j)) = .TRUE. after ordering, since ordering
  111.              may change the value of complex eigenvalues (especially if the
  112.              eigenvalue is ill-conditioned), in this case INFO is set to N+2
  113.              (See INFO below).
  114.  
  115.      N       (input) INTEGER
  116.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  117.  
  118.      A       (input/output) COMPLEX*16 array, dimension (LDA, N)
  119.              On entry, the first of the pair of matrices.  On exit, A has been
  120.              overwritten by its generalized Schur form S.
  121.  
  122.      LDA     (input) INTEGER
  123.              The leading dimension of A.  LDA >= max(1,N).
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))                                                            ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      B       (input/output) COMPLEX*16 array, dimension (LDB, N)
  141.              On entry, the second of the pair of matrices.  On exit, B has
  142.              been overwritten by its generalized Schur form T.
  143.  
  144.      LDB     (input) INTEGER
  145.              The leading dimension of B.  LDB >= max(1,N).
  146.  
  147.      SDIM    (output) INTEGER
  148.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  149.              eigenvalues (after sorting) for which DELCTG is true.
  150.  
  151.      ALPHA   (output) COMPLEX*16 array, dimension (N)
  152.              BETA    (output) COMPLEX*16 array, dimension (N) On exit,
  153.              ALPHA(j)/BETA(j), j=1,...,N, will be the generalized eigenvalues.
  154.              ALPHA(j), j=1,...,N  and  BETA(j), j=1,...,N  are the diagonals
  155.              of the complex Schur form (A,B) output by ZGGES. The  BETA(j)
  156.              will be non-negative real.
  157.  
  158.              Note: the quotients ALPHA(j)/BETA(j) may easily over- or
  159.              underflow, and BETA(j) may even be zero.  Thus, the user should
  160.              avoid naively computing the ratio alpha/beta.  However, ALPHA
  161.              will be always less than and usually comparable with norm(A) in
  162.              magnitude, and BETA always less than and usually comparable with
  163.              norm(B).
  164.  
  165.      VSL     (output) COMPLEX*16 array, dimension (LDVSL,N)
  166.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  Not
  167.              referenced if JOBVSL = 'N'.
  168.  
  169.      LDVSL   (input) INTEGER
  170.              The leading dimension of the matrix VSL. LDVSL >= 1, and if
  171.              JOBVSL = 'V', LDVSL >= N.
  172.  
  173.      VSR     (output) COMPLEX*16 array, dimension (LDVSR,N)
  174.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  Not
  175.              referenced if JOBVSR = 'N'.
  176.  
  177.      LDVSR   (input) INTEGER
  178.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  179.              JOBVSR = 'V', LDVSR >= N.
  180.  
  181.      WORK    (workspace/output) COMPLEX*16 array, dimension (LWORK)
  182.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  183.  
  184.      LWORK   (input) INTEGER
  185.              The dimension of the array WORK.  LWORK >= max(1,2*N).  For good
  186.              performance, LWORK must generally be larger.
  187.  
  188.              If LWORK = -1, then a workspace query is assumed; the routine
  189.              only calculates the optimal size of the WORK array, returns this
  190.              value as the first entry of the WORK array, and no error message
  191.              related to LWORK is issued by XERBLA.
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))                                                            ZZZZGGGGGGGGEEEESSSS((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      RWORK   (workspace) DOUBLE PRECISION array, dimension (8*N)
  207.  
  208.      BWORK   (workspace) LOGICAL array, dimension (N)
  209.              Not referenced if SORT = 'N'.
  210.  
  211.      INFO    (output) INTEGER
  212.              = 0:  successful exit
  213.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  214.              =1,...,N:  The QZ iteration failed.  (A,B) are not in Schur form,
  215.              but ALPHA(j) and BETA(j) should be correct for j=INFO+1,...,N.  >
  216.              N:  =N+1: other than QZ iteration failed in ZHGEQZ
  217.              =N+2: after reordering, roundoff changed values of some complex
  218.              eigenvalues so that leading eigenvalues in the Generalized Schur
  219.              form no longer satisfy DELCTG=.TRUE.  This could also be caused
  220.              due to scaling.  =N+3: reordering falied in ZTGSEN.
  221.  
  222. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  223.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  224.  
  225.      This man page is available only online.
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.